ConferenceLine

The ConferenceLine API procedure is used to add an "active call" to a conference session. An "active call" is any phone line that is in the SipInCall state. Note that conferencing capabilities are only possible on versions of the telephony engine that support two or more phone lines and when licensing allows conferencing to be enabled.

The simplest form of conferencing occurs when you have two simultaneous phone calls active. You could be talking to one of the parties while the other is on hold. Alternatively, both calls could be placed on hold. To create a conference session with you and the two other parties, you would call the ConferenceLine API procedure using the appropriate phone line each call is assigned to. Once both active phone lines are added to the conference session, all parties will be able to talk and hear each other using full duplex audio.

As an added benefit, the telephony engine’s conferencing functions automatically handle the details associated with conferencing parties that are using different audio formats and rates. Your application software does not have to perform any other operation other than to specify who should be included in the conference session.

While in a conference session, any line can be placed on hold or terminated. If one of the conference participants is placed on hold, they can be brought back into the conference session at a later time by calling ConferenceLine again on that particular phone line.

Once you have established a conference session, you can terminate the session by placing all conference session phone lines on hold or by hanging up the lines.

TELEPHONY_RETURN_VALUE ConferenceLine(

SIPHANDLE hStateMachine,

int PhoneLine,

BOOL ConferenceState

);

Parameters:

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

PhoneLine

[in] The zero based phone line to place into the conference mode.

ConferenceState

[in] Specifies the conference state of the phone line. If TRUE, the phone line is added to a conference session. If FALSE, the phone line will be removed from the conference session and will transition back to the hold state.

Return Value:

If the function succeeds, the return value will be SipSuccess.

If the function fails, the return value will be one of the following values as specified by the TELEPHONY_RETURN_VALUE data type.

Value	Description
SipCallFailure	This is a generic "catch all" API error. If an error condition is not specified by any other API error value, this error will be returned.
SipInvalidHandle	An API procedure was passed an invalid handle. The telephony engine attempts to verify user specified telephony handles and returns this error when an invalid handle is detected.
SipBadPhoneLine	A telephony operation was specified using an invalid phone line. Phone lines are numbered starting from zero.
SipNoCallActive	An API operation was being performed on a phone line. However, there is no active call on the specified phone line.
SipConferenceNotEnabled	Call conferencing is not enabled. For additional details, see the CallConferenceEnabled startup parameter in the START_SIP_TELEPHONY_PARAMS startup structure.

Remarks:

Call conference support must be enabled in the media engine when it is started. Your media engine license must also support call conference capabilities. For additional details, see the CallConferenceEnabled startup parameter in the START_SIP_TELEPHONY_PARAMS startup structure.

The conferencing capabilities of the VOIP Media Engine™ are extremely powerful yet easy to use. For additional details associate with conference call sessions and conference group IDs, see the SetConferenceGroupIds API procedure.